<!DOCTYPE html>
<html lang="en-US">
<head>
    <meta charset="UTF-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="language" content="en" />
        <link href="./assets/ffd55088/css/bootstrap.css" rel="stylesheet">
<link href="./assets/5cf9384a/solarized_light.css" rel="stylesheet">
<link href="./assets/6c54116e/style.css" rel="stylesheet">
<script src="./assets/a44cef0f/jquery.js"></script>
<script src="./assets/ffd55088/js/bootstrap.js"></script>
<script src="./assets/8ac4e28a/jssearch.js"></script>    <title>Logging - Handling Requests - The Definitive Guide to Yii 2.0</title>
</head>
<body>

<div class="wrap">
    <nav id="w453" class="navbar-inverse navbar-fixed-top navbar" role="navigation"><div class="navbar-header"><button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#w453-collapse"><span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span></button><a class="navbar-brand" href="./index.html">The Definitive Guide to Yii 2.0</a></div><div id="w453-collapse" class="collapse navbar-collapse"><ul id="w454" class="navbar-nav nav"><li><a href="./index.html">Class reference</a></li>
<li class="dropdown"><a class="dropdown-toggle" href="#" data-toggle="dropdown">Extensions <b class="caret"></b></a><ul id="w455" class="dropdown-menu"><li><a href="./ext-apidoc-index.html" tabindex="-1">apidoc</a></li>
<li><a href="./ext-authclient-index.html" tabindex="-1">authclient</a></li>
<li><a href="./ext-bootstrap-index.html" tabindex="-1">bootstrap</a></li>
<li><a href="./ext-codeception-index.html" tabindex="-1">codeception</a></li>
<li><a href="./ext-debug-index.html" tabindex="-1">debug</a></li>
<li><a href="./ext-elasticsearch-index.html" tabindex="-1">elasticsearch</a></li>
<li><a href="./ext-faker-index.html" tabindex="-1">faker</a></li>
<li><a href="./ext-gii-index.html" tabindex="-1">gii</a></li>
<li><a href="./ext-imagine-index.html" tabindex="-1">imagine</a></li>
<li><a href="./ext-jui-index.html" tabindex="-1">jui</a></li>
<li><a href="./ext-mongodb-index.html" tabindex="-1">mongodb</a></li>
<li><a href="./ext-redis-index.html" tabindex="-1">redis</a></li>
<li><a href="./ext-smarty-index.html" tabindex="-1">smarty</a></li>
<li><a href="./ext-sphinx-index.html" tabindex="-1">sphinx</a></li>
<li><a href="./ext-swiftmailer-index.html" tabindex="-1">swiftmailer</a></li>
<li><a href="./ext-twig-index.html" tabindex="-1">twig</a></li></ul></li>
<li><a href="./guide-README.html">Guide</a></li></ul><div class="navbar-form navbar-left" role="search">
  <div class="form-group">
    <input id="searchbox" type="text" class="form-control" placeholder="Search">
  </div>
</div>
</div></nav>
    <div id="search-resultbox" style="display: none;" class="modal-content">
        <ul id="search-results">
        </ul>
    </div>

    
<div class="row">
    <div class="col-md-2">
                <div id="navigation" class="list-group"><a class="list-group-item" href="#navigation-437" data-toggle="collapse" data-parent="#navigation">Introduction <b class="caret"></b></a><div id="navigation-437" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-intro-yii.html">About Yii</a>
<a class="list-group-item" href="./guide-intro-upgrade-from-v1.html">Upgrading from Version 1.1</a></div>
<a class="list-group-item" href="#navigation-438" data-toggle="collapse" data-parent="#navigation">Getting Started <b class="caret"></b></a><div id="navigation-438" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-start-installation.html">Installing Yii</a>
<a class="list-group-item" href="./guide-start-workflow.html">Running Applications</a>
<a class="list-group-item" href="./guide-start-hello.html">Saying Hello</a>
<a class="list-group-item" href="./guide-start-forms.html">Working with Forms</a>
<a class="list-group-item" href="./guide-start-databases.html">Working with Databases</a>
<a class="list-group-item" href="./guide-start-gii.html">Generating Code with Gii</a>
<a class="list-group-item" href="./guide-start-looking-ahead.html">Looking Ahead</a></div>
<a class="list-group-item" href="#navigation-439" data-toggle="collapse" data-parent="#navigation">Application Structure <b class="caret"></b></a><div id="navigation-439" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-structure-overview.html">Overview</a>
<a class="list-group-item" href="./guide-structure-entry-scripts.html">Entry Scripts</a>
<a class="list-group-item" href="./guide-structure-applications.html">Applications</a>
<a class="list-group-item" href="./guide-structure-application-components.html">Application Components</a>
<a class="list-group-item" href="./guide-structure-controllers.html">Controllers</a>
<a class="list-group-item" href="./guide-structure-models.html">Models</a>
<a class="list-group-item" href="./guide-structure-views.html">Views</a>
<a class="list-group-item" href="./guide-structure-modules.html">Modules</a>
<a class="list-group-item" href="./guide-structure-filters.html">Filters</a>
<a class="list-group-item" href="./guide-structure-widgets.html">Widgets</a>
<a class="list-group-item" href="./guide-structure-assets.html">Assets</a>
<a class="list-group-item" href="./guide-structure-extensions.html">Extensions</a></div>
<a class="list-group-item active" href="#navigation-440" data-toggle="collapse" data-parent="#navigation">Handling Requests <b class="caret"></b></a><div id="navigation-440" class="submenu panel-collapse collapse in"><a class="list-group-item" href="./guide-runtime-overview.html">Overview</a>
<a class="list-group-item" href="./guide-runtime-bootstrapping.html">Bootstrapping</a>
<a class="list-group-item" href="./guide-runtime-routing.html">Routing and URL Creation</a>
<a class="list-group-item" href="./guide-runtime-requests.html">Requests</a>
<a class="list-group-item" href="./guide-runtime-responses.html">Responses</a>
<a class="list-group-item" href="./guide-runtime-sessions-cookies.html">Sessions and Cookies</a>
<a class="list-group-item" href="./guide-runtime-handling-errors.html">Handling Errors</a>
<a class="list-group-item active" href="./guide-runtime-logging.html">Logging</a></div>
<a class="list-group-item" href="#navigation-441" data-toggle="collapse" data-parent="#navigation">Key Concepts <b class="caret"></b></a><div id="navigation-441" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-concept-components.html">Components</a>
<a class="list-group-item" href="./guide-concept-properties.html">Properties</a>
<a class="list-group-item" href="./guide-concept-events.html">Events</a>
<a class="list-group-item" href="./guide-concept-behaviors.html">Behaviors</a>
<a class="list-group-item" href="./guide-concept-configurations.html">Configurations</a>
<a class="list-group-item" href="./guide-concept-aliases.html">Aliases</a>
<a class="list-group-item" href="./guide-concept-autoloading.html">Class Autoloading</a>
<a class="list-group-item" href="./guide-concept-service-locator.html">Service Locator</a>
<a class="list-group-item" href="./guide-concept-di-container.html">Dependency Injection Container</a></div>
<a class="list-group-item" href="#navigation-442" data-toggle="collapse" data-parent="#navigation">Working with Databases <b class="caret"></b></a><div id="navigation-442" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-db-dao.html">Data Access Objects</a>
<a class="list-group-item" href="./guide-db-query-builder.html">Query Builder</a>
<a class="list-group-item" href="./guide-db-active-record.html">Active Record</a>
<a class="list-group-item" href="./guide-db-migrations.html">Migrations</a>
<a class="list-group-item" href="https://github.com/yiisoft/yii2-sphinx/blob/master/docs/guide/README.md">Sphinx</a>
<a class="list-group-item" href="https://github.com/yiisoft/yii2-redis/blob/master/docs/guide/README.md">Redis</a>
<a class="list-group-item" href="https://github.com/yiisoft/yii2-mongodb/blob/master/docs/guide/README.md">MongoDB</a>
<a class="list-group-item" href="https://github.com/yiisoft/yii2-elasticsearch/blob/master/docs/guide/README.md">ElasticSearch</a></div>
<a class="list-group-item" href="#navigation-443" data-toggle="collapse" data-parent="#navigation">Getting Data from Users <b class="caret"></b></a><div id="navigation-443" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-input-forms.html">Creating Forms</a>
<a class="list-group-item" href="./guide-input-validation.html">Validating Input</a>
<a class="list-group-item" href="./guide-input-file-upload.html">Uploading Files</a>
<a class="list-group-item" href="./guide-input-tabular-input.html">Collecting Tabular Input</a>
<a class="list-group-item" href="./guide-input-multiple-models.html">Getting Data for Multiple Models</a></div>
<a class="list-group-item" href="#navigation-444" data-toggle="collapse" data-parent="#navigation">Displaying Data <b class="caret"></b></a><div id="navigation-444" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-output-formatting.html">Data Formatting</a>
<a class="list-group-item" href="./guide-output-pagination.html">Pagination</a>
<a class="list-group-item" href="./guide-output-sorting.html">Sorting</a>
<a class="list-group-item" href="./guide-output-data-providers.html">Data Providers</a>
<a class="list-group-item" href="./guide-output-data-widgets.html">Data Widgets</a>
<a class="list-group-item" href="./guide-output-client-scripts.html">Working with Client Scripts</a>
<a class="list-group-item" href="./guide-output-theming.html">Theming</a></div>
<a class="list-group-item" href="#navigation-445" data-toggle="collapse" data-parent="#navigation">Security <b class="caret"></b></a><div id="navigation-445" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-security-overview.html">Overview</a>
<a class="list-group-item" href="./guide-security-authentication.html">Authentication</a>
<a class="list-group-item" href="./guide-security-authorization.html">Authorization</a>
<a class="list-group-item" href="./guide-security-passwords.html">Working with Passwords</a>
<a class="list-group-item" href="./guide-security-cryptography.html">Cryptography</a>
<a class="list-group-item" href="./guide-structure-views.html#security">Views security</a>
<a class="list-group-item" href="https://github.com/yiisoft/yii2-authclient/blob/master/docs/guide/README.md">Auth Clients</a>
<a class="list-group-item" href="./guide-security-best-practices.html">Best Practices</a></div>
<a class="list-group-item" href="#navigation-446" data-toggle="collapse" data-parent="#navigation">Caching <b class="caret"></b></a><div id="navigation-446" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-caching-overview.html">Overview</a>
<a class="list-group-item" href="./guide-caching-data.html">Data Caching</a>
<a class="list-group-item" href="./guide-caching-fragment.html">Fragment Caching</a>
<a class="list-group-item" href="./guide-caching-page.html">Page Caching</a>
<a class="list-group-item" href="./guide-caching-http.html">HTTP Caching</a></div>
<a class="list-group-item" href="#navigation-447" data-toggle="collapse" data-parent="#navigation">RESTful Web Services <b class="caret"></b></a><div id="navigation-447" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-rest-quick-start.html">Quick Start</a>
<a class="list-group-item" href="./guide-rest-resources.html">Resources</a>
<a class="list-group-item" href="./guide-rest-controllers.html">Controllers</a>
<a class="list-group-item" href="./guide-rest-routing.html">Routing</a>
<a class="list-group-item" href="./guide-rest-response-formatting.html">Response Formatting</a>
<a class="list-group-item" href="./guide-rest-authentication.html">Authentication</a>
<a class="list-group-item" href="./guide-rest-rate-limiting.html">Rate Limiting</a>
<a class="list-group-item" href="./guide-rest-versioning.html">Versioning</a>
<a class="list-group-item" href="./guide-rest-error-handling.html">Error Handling</a></div>
<a class="list-group-item" href="#navigation-448" data-toggle="collapse" data-parent="#navigation">Development Tools <b class="caret"></b></a><div id="navigation-448" class="submenu panel-collapse collapse"><a class="list-group-item" href="https://github.com/yiisoft/yii2-debug/blob/master/docs/guide/README.md">Debug Toolbar and Debugger</a>
<a class="list-group-item" href="https://github.com/yiisoft/yii2-gii/blob/master/docs/guide/README.md">Generating Code using Gii</a>
<a class="list-group-item" href="https://github.com/yiisoft/yii2-apidoc">Generating API Documentation</a></div>
<a class="list-group-item" href="#navigation-449" data-toggle="collapse" data-parent="#navigation">Testing <b class="caret"></b></a><div id="navigation-449" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-test-overview.html">Overview</a>
<a class="list-group-item" href="./guide-test-environment-setup.html">Testing environment setup</a>
<a class="list-group-item" href="./guide-test-unit.html">Unit Tests</a>
<a class="list-group-item" href="./guide-test-functional.html">Functional Tests</a>
<a class="list-group-item" href="./guide-test-acceptance.html">Acceptance Tests</a>
<a class="list-group-item" href="./guide-test-fixtures.html">Fixtures</a></div>
<a class="list-group-item" href="#navigation-450" data-toggle="collapse" data-parent="#navigation">Special Topics <b class="caret"></b></a><div id="navigation-450" class="submenu panel-collapse collapse"><a class="list-group-item" href="https://github.com/yiisoft/yii2-app-advanced/blob/master/docs/guide/README.md">Advanced Project Template</a>
<a class="list-group-item" href="./guide-tutorial-start-from-scratch.html">Building Application from Scratch</a>
<a class="list-group-item" href="./guide-tutorial-console.html">Console Commands</a>
<a class="list-group-item" href="./guide-tutorial-core-validators.html">Core Validators</a>
<a class="list-group-item" href="./guide-tutorial-i18n.html">Internationalization</a>
<a class="list-group-item" href="./guide-tutorial-mailing.html">Mailing</a>
<a class="list-group-item" href="./guide-tutorial-performance-tuning.html">Performance Tuning</a>
<a class="list-group-item" href="./guide-tutorial-shared-hosting.html">Shared Hosting Environment</a>
<a class="list-group-item" href="./guide-tutorial-template-engines.html">Template Engines</a>
<a class="list-group-item" href="./guide-tutorial-yii-integration.html">Working with Third-Party Code</a></div>
<a class="list-group-item" href="#navigation-451" data-toggle="collapse" data-parent="#navigation">Widgets <b class="caret"></b></a><div id="navigation-451" class="submenu panel-collapse collapse"><a class="list-group-item" href="https://github.com/yiisoft/yii2-bootstrap/blob/master/docs/guide/README.md">Bootstrap Widgets</a>
<a class="list-group-item" href="https://github.com/yiisoft/yii2-jui/blob/master/docs/guide/README.md">jQuery UI Widgets</a></div>
<a class="list-group-item" href="#navigation-452" data-toggle="collapse" data-parent="#navigation">Helpers <b class="caret"></b></a><div id="navigation-452" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-helper-overview.html">Overview</a>
<a class="list-group-item" href="./guide-helper-array.html">ArrayHelper</a>
<a class="list-group-item" href="./guide-helper-html.html">Html</a>
<a class="list-group-item" href="./guide-helper-url.html">Url</a></div></div>    </div>
    <div class="col-md-9 guide-content" role="main">
        <h1>Logging <span id="logging"></span><a href="#logging" class="hashlink">&para;</a></h1>
<div class="toc"><ol><li><a href="#log-messages">Log Messages</a></li>
<li><a href="#log-targets">Log Targets</a></li>
<li><a href="#performance-profiling">Performance Profiling</a></li></ol></div>
<p>Yii provides a powerful logging framework that is highly customizable and extensible. Using this framework, you
can easily log various types of messages, filter them, and gather them at different targets, such as files, databases,
emails. </p>
<p>Using the Yii logging framework involves the following steps:</p>
<ul>
<li>Record <a href="#log-messages">log messages</a> at various places in your code;</li>
<li>Configure <a href="#log-targets">log targets</a> in the application configuration to filter and export log messages;</li>
<li>Examine the filtered logged messages exported by different targets (e.g. the <a href="guide-tool-debugger.html">Yii debugger</a>).</li>
</ul>
<p>In this section, we will mainly describe the first two steps.</p>
<h2>Log Messages  <span id="log-messages"></span><a href="#log-messages" class="hashlink">&para;</a></h2><p>Recording log messages is as simple as calling one of the following logging methods:</p>
<ul>
<li><a href="./yii-baseyii.html#trace()-detail">Yii::trace()</a>: record a message to trace how a piece of code runs. This is mainly for development use.</li>
<li><a href="./yii-baseyii.html#info()-detail">Yii::info()</a>: record a message that conveys some useful information.</li>
<li><a href="./yii-baseyii.html#warning()-detail">Yii::warning()</a>: record a warning message that indicates something unexpected has happened.</li>
<li><a href="./yii-baseyii.html#error()-detail">Yii::error()</a>: record a fatal error that should be investigated as soon as possible.</li>
</ul>
<p>These logging methods record log messages at various <em>severity levels</em> and <em>categories</em>. They share
the same function signature <code>function ($message, $category = 'application')</code>, where <code>$message</code> stands for
the log message to be recorded, while <code>$category</code> is the category of the log message. The code in the following
example records a trace message under the default category <code>application</code>:</p>
<pre><code class="hljs php language-php">Yii::trace(<span class="hljs-string">'start calculating average revenue'</span>);
</code></pre>
<blockquote class="info"><p><strong>Info: </strong>Log messages can be strings as well as complex data, such as arrays or objects. It is the responsibility
of <a href="#log-targets">log targets</a> to properly deal with log messages. By default, if a log message is not a string,
it will be exported as a string by calling <a href="./yii-helpers-basevardumper.html#export()-detail">yii\helpers\VarDumper::export()</a>.</p>
</blockquote>
<p>To better organize and filter log messages, it is recommended that you specify an appropriate category for each
log message. You may choose a hierarchical naming scheme for categories, which will make it easier for 
<a href="#log-targets">log targets</a> to filter messages based on their categories. A simple yet effective naming scheme
is to use the PHP magic constant <code>__METHOD__</code> for the category names. This is also the approach used in the core 
Yii framework code. For example,</p>
<pre><code class="hljs php language-php">Yii::trace(<span class="hljs-string">'start calculating average revenue'</span>, <span class="hljs-keyword">__METHOD__</span>);
</code></pre>
<p>The <code>__METHOD__</code> constant evaluates as the name of the method (prefixed with the fully qualified class name) where 
the constant appears. For example, it is equal to the string <code>'app\controllers\RevenueController::calculate'</code> if 
the above line of code is called within this method.</p>
<blockquote class="info"><p><strong>Info: </strong>The logging methods described above are actually shortcuts to the <a href="./yii-log-logger.html#log()-detail">log()</a> method 
of the <a href="./yii-log-logger.html">logger object</a> which is a singleton accessible through the expression <code>Yii::getLogger()</code>. When
enough messages are logged or when the application ends, the logger object will call a 
<a href="./yii-log-dispatcher.html">message dispatcher</a> to send recorded log messages to the registered <a href="#log-targets">log targets</a>.</p>
</blockquote>
<h2>Log Targets  <span id="log-targets"></span><a href="#log-targets" class="hashlink">&para;</a></h2><p>A log target is an instance of the <a href="./yii-log-target.html">yii\log\Target</a> class or its child class. It filters the log messages by their
severity levels and categories and then exports them to some medium. For example, a <a href="./yii-log-dbtarget.html">database target</a>
exports the filtered log messages to a database table, while an <a href="./yii-log-emailtarget.html">email target</a> exports
the log messages to specified email addresses.</p>
<p>You can register multiple log targets in an application by configuring them through the <code>log</code> <a href="guide-structure-application-components.html">application component</a>
in the application configuration, like the following:</p>
<pre><code class="hljs php language-php"><span class="hljs-keyword">return</span> [
    <span class="hljs-comment">// the "log" component must be loaded during bootstrapping time</span>
    <span class="hljs-string">'bootstrap'</span> =&gt; [<span class="hljs-string">'log'</span>],
    
    <span class="hljs-string">'components'</span> =&gt; [
        <span class="hljs-string">'log'</span> =&gt; [
            <span class="hljs-string">'targets'</span> =&gt; [
                [
                    <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\log\DbTarget'</span>,
                    <span class="hljs-string">'levels'</span> =&gt; [<span class="hljs-string">'error'</span>, <span class="hljs-string">'warning'</span>],
                ],
                [
                    <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\log\EmailTarget'</span>,
                    <span class="hljs-string">'levels'</span> =&gt; [<span class="hljs-string">'error'</span>],
                    <span class="hljs-string">'categories'</span> =&gt; [<span class="hljs-string">'yii\db\*'</span>],
                    <span class="hljs-string">'message'</span> =&gt; [
                       <span class="hljs-string">'from'</span> =&gt; [<span class="hljs-string">'log@example.com'</span>],
                       <span class="hljs-string">'to'</span> =&gt; [<span class="hljs-string">'admin@example.com'</span>, <span class="hljs-string">'developer@example.com'</span>],
                       <span class="hljs-string">'subject'</span> =&gt; <span class="hljs-string">'Database errors at example.com'</span>,
                    ],
                ],
            ],
        ],
    ],
];
</code></pre>
<blockquote class="note"><p><strong>Note: </strong>The <code>log</code> component must be loaded during <a href="guide-runtime-bootstrapping.html">bootstrapping</a> time so that
it can dispatch log messages to targets promptly. That is why it is listed in the <code>bootstrap</code> array as shown above.</p>
</blockquote>
<p>In the above code, two log targets are registered in the <a href="./yii-log-dispatcher.html#$targets-detail">yii\log\Dispatcher::$targets</a> property: </p>
<ul>
<li>the first target selects error and warning messages and saves them in a database table;</li>
<li>the second target selects error messages under the categories whose names start with <code>yii\db\</code>, and sends
them in an email to both <code>admin@example.com</code> and <code>developer@example.com</code>.</li>
</ul>
<p>Yii comes with the following built-in log targets. Please refer to the API documentation about these classes to 
learn how to configure and use them. </p>
<ul>
<li><a href="./yii-log-dbtarget.html">yii\log\DbTarget</a>: stores log messages in a database table.</li>
<li><a href="./yii-log-emailtarget.html">yii\log\EmailTarget</a>: sends log messages to pre-specified email addresses.</li>
<li><a href="./yii-log-filetarget.html">yii\log\FileTarget</a>: saves log messages in files.</li>
<li><a href="./yii-log-syslogtarget.html">yii\log\SyslogTarget</a>: saves log messages to syslog by calling the PHP function <code>syslog()</code>.</li>
</ul>
<p>In the following, we will describe the features common to all log targets.</p>
<h3>Message Filtering  <span id="message-filtering"></span><a href="#message-filtering" class="hashlink">&para;</a></h3><p>For each log target, you can configure its <a href="./yii-log-target.html#$levels-detail">levels</a> and 
<a href="./yii-log-target.html#$categories-detail">categories</a> properties to specify which severity levels and categories of the messages the target should process.</p>
<p>The <a href="./yii-log-target.html#$levels-detail">levels</a> property takes an array consisting of one or several of the following values:</p>
<ul>
<li><code>error</code>: corresponding to messages logged by <a href="./yii-baseyii.html#error()-detail">Yii::error()</a>.</li>
<li><code>warning</code>: corresponding to messages logged by <a href="./yii-baseyii.html#warning()-detail">Yii::warning()</a>.</li>
<li><code>info</code>: corresponding to messages logged by <a href="./yii-baseyii.html#info()-detail">Yii::info()</a>.</li>
<li><code>trace</code>: corresponding to messages logged by <a href="./yii-baseyii.html#trace()-detail">Yii::trace()</a>.</li>
<li><code>profile</code>: corresponding to messages logged by <a href="./yii-baseyii.html#beginProfile()-detail">Yii::beginProfile()</a> and <a href="./yii-baseyii.html#endProfile()-detail">Yii::endProfile()</a>, which will
be explained in more details in the <a href="#performance-profiling">Profiling</a> subsection.</li>
</ul>
<p>If you do not specify the <a href="./yii-log-target.html#$levels-detail">levels</a> property, it means the target will process messages
of <em>any</em> severity level.</p>
<p>The <a href="./yii-log-target.html#$categories-detail">categories</a> property takes an array consisting of message category names or patterns.
A target will only process messages whose category can be found or match one of the patterns in this array.
A category pattern is a category name prefix with an asterisk <code>*</code> at its end. A category name matches a category pattern
if it starts with the same prefix of the pattern. For example, <code>yii\db\Command::execute</code> and <code>yii\db\Command::query</code>
are used as category names for the log messages recorded in the <a href="./yii-db-command.html">yii\db\Command</a> class. They both match
the pattern <code>yii\db\*</code>.</p>
<p>If you do not specify the <a href="./yii-log-target.html#$categories-detail">categories</a> property, it means the target will process
messages of <em>any</em> category.</p>
<p>Besides whitelisting the categories by the <a href="./yii-log-target.html#$categories-detail">categories</a> property, you may also
blacklist certain categories by the <a href="./yii-log-target.html#$except-detail">except</a> property. If the category of a message
is found or matches one of the patterns in this property, it will NOT be processed by the target.</p>
<p>The following target configuration specifies that the target should only process error and warning messages
under the categories whose names match either <code>yii\db\*</code> or <code>yii\web\HttpException:*</code>, but not <code>yii\web\HttpException:404</code>.</p>
<pre><code class="hljs php language-php">[
    <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\log\FileTarget'</span>,
    <span class="hljs-string">'levels'</span> =&gt; [<span class="hljs-string">'error'</span>, <span class="hljs-string">'warning'</span>],
    <span class="hljs-string">'categories'</span> =&gt; [
        <span class="hljs-string">'yii\db\*'</span>,
        <span class="hljs-string">'yii\web\HttpException:*'</span>,
    ],
    <span class="hljs-string">'except'</span> =&gt; [
        <span class="hljs-string">'yii\web\HttpException:404'</span>,
    ],
]
</code></pre>
<blockquote class="info"><p><strong>Info: </strong>When an HTTP exception is caught by the <a href="guide-runtime-handling-errors.html">error handler</a>, an error message
  will be logged with the category name in the format of <code>yii\web\HttpException:ErrorCode</code>. For example,
  the <a href="./yii-web-notfoundhttpexception.html">yii\web\NotFoundHttpException</a> will cause an error message of category <code>yii\web\HttpException:404</code>.</p>
</blockquote>
<h3>Message Formatting  <span id="message-formatting"></span><a href="#message-formatting" class="hashlink">&para;</a></h3><p>Log targets export the filtered log messages in a certain format. For example, if you install
a log target of the class <a href="./yii-log-filetarget.html">yii\log\FileTarget</a>, you may find a log message similar to the following in the
<code>runtime/log/app.log</code> file:</p>
<pre><code class="hljs markdown">2014-10-04 18:10:15 [<span class="hljs-link_label">::1</span>][<span class="hljs-link_reference"></span>][<span class="hljs-link_label">-</span>][<span class="hljs-link_reference">trace</span>][<span class="hljs-link_label">yii\base\Module::getModule</span>] Loading module: debug
</code></pre>
<p>By default, log messages will be formatted as follows by the <a href="./yii-log-target.html#formatMessage()-detail">yii\log\Target::formatMessage()</a>:</p>
<pre><code class="hljs markdown">Timestamp [<span class="hljs-link_label">IP address</span>][<span class="hljs-link_reference">User ID</span>][<span class="hljs-link_label">Session ID</span>][<span class="hljs-link_reference">Severity Level</span>][<span class="hljs-link_label">Category</span>] Message Text
</code></pre>
<p>You may customize this format by configuring the <a href="./yii-log-target.html#$prefix-detail">yii\log\Target::$prefix</a> property which takes a PHP callable
returning a customized message prefix. For example, the following code configures a log target to prefix each
log message with the current user ID (IP address and Session ID are removed for privacy reasons).</p>
<pre><code class="hljs php language-php">[
    <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\log\FileTarget'</span>,
    <span class="hljs-string">'prefix'</span> =&gt; <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">(<span class="hljs-variable">$message</span>)</span> </span>{
        <span class="hljs-variable">$user</span> = Yii::<span class="hljs-variable">$app</span>-&gt;has(<span class="hljs-string">'user'</span>, <span class="hljs-keyword">true</span>) ? Yii::<span class="hljs-variable">$app</span>-&gt;get(<span class="hljs-string">'user'</span>) : <span class="hljs-keyword">null</span>;
        <span class="hljs-variable">$userID</span> = <span class="hljs-variable">$user</span> ? <span class="hljs-variable">$user</span>-&gt;getId(<span class="hljs-keyword">false</span>) : <span class="hljs-string">'-'</span>;
        <span class="hljs-keyword">return</span> <span class="hljs-string">"[$userID]"</span>;
    }
]
</code></pre>
<p>Besides message prefixes, log targets also append some context information to each batch of log messages.
By default, the values of these global PHP variables are included: <code>$_GET</code>, <code>$_POST</code>, <code>$_FILES</code>, <code>$_COOKIE</code>,
<code>$_SESSION</code> and <code>$_SERVER</code>. You may adjust this behavior by configuring the <a href="./yii-log-target.html#$logVars-detail">yii\log\Target::$logVars</a> property
with the names of the global variables that you want to include by the log target. For example, the following
log target configuration specifies that only the value of the <code>$_SERVER</code> variable will be appended to the log messages.</p>
<pre><code class="hljs php language-php">[
    <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\log\FileTarget'</span>,
    <span class="hljs-string">'logVars'</span> =&gt; [<span class="hljs-string">'_SERVER'</span>],
]
</code></pre>
<p>You may configure <code>logVars</code> to be an empty array to totally disable the inclusion of context information.
Or if you want to implement your own way of providing context information, you may override the
<a href="./yii-log-target.html#getContextMessage()-detail">yii\log\Target::getContextMessage()</a> method.</p>
<h3>Message Trace Level  <span id="trace-level"></span><a href="#trace-level" class="hashlink">&para;</a></h3><p>During development, it is often desirable to see where each log message is coming from. This can be achieved by
configuring the <a href="./yii-log-dispatcher.html#$traceLevel-detail">traceLevel</a> property of the <code>log</code> component like the following:</p>
<pre><code class="hljs php language-php"><span class="hljs-keyword">return</span> [
    <span class="hljs-string">'bootstrap'</span> =&gt; [<span class="hljs-string">'log'</span>],
    <span class="hljs-string">'components'</span> =&gt; [
        <span class="hljs-string">'log'</span> =&gt; [
            <span class="hljs-string">'traceLevel'</span> =&gt; YII_DEBUG ? <span class="hljs-number">3</span> : <span class="hljs-number">0</span>,
            <span class="hljs-string">'targets'</span> =&gt; [...],
        ],
    ],
];
</code></pre>
<p>The above application configuration sets <a href="./yii-log-dispatcher.html#$traceLevel-detail">traceLevel</a> to be 3 if <code>YII_DEBUG</code> is on
and 0 if <code>YII_DEBUG</code> is off. This means, if <code>YII_DEBUG</code> is on, each log message will be appended with at most 3
levels of the call stack at which the log message is recorded; and if <code>YII_DEBUG</code> is off, no call stack information
will be included.</p>
<blockquote class="info"><p><strong>Info: </strong>Getting call stack information is not trivial. Therefore, you should only use this feature during development
or when debugging an application.</p>
</blockquote>
<h3>Message Flushing and Exporting  <span id="flushing-exporting"></span><a href="#flushing-exporting" class="hashlink">&para;</a></h3><p>As aforementioned, log messages are maintained in an array by the <a href="./yii-log-logger.html">logger object</a>. To limit the
memory consumption by this array, the logger will flush the recorded messages to the <a href="#log-targets">log targets</a>
each time the array accumulates a certain number of log messages. You can customize this number by configuring
the <a href="./yii-log-dispatcher.html#$flushInterval-detail">flushInterval</a> property of the <code>log</code> component:</p>
<pre><code class="hljs php language-php"><span class="hljs-keyword">return</span> [
    <span class="hljs-string">'bootstrap'</span> =&gt; [<span class="hljs-string">'log'</span>],
    <span class="hljs-string">'components'</span> =&gt; [
        <span class="hljs-string">'log'</span> =&gt; [
            <span class="hljs-string">'flushInterval'</span> =&gt; <span class="hljs-number">100</span>,   <span class="hljs-comment">// default is 1000</span>
            <span class="hljs-string">'targets'</span> =&gt; [...],
        ],
    ],
];
</code></pre>
<blockquote class="info"><p><strong>Info: </strong>Message flushing also occurs when the application ends, which ensures log targets can receive complete log messages.</p>
</blockquote>
<p>When the <a href="./yii-log-logger.html">logger object</a> flushes log messages to <a href="#log-targets">log targets</a>, they do not get exported
immediately. Instead, the message exporting only occurs when a log target accumulates certain number of the filtered
messages. You can customize this number by configuring the <a href="./yii-log-target.html#$exportInterval-detail">exportInterval</a>
property of individual <a href="#log-targets">log targets</a>, like the following,</p>
<pre><code class="hljs php language-php">[
    <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\log\FileTarget'</span>,
    <span class="hljs-string">'exportInterval'</span> =&gt; <span class="hljs-number">100</span>,  <span class="hljs-comment">// default is 1000</span>
]
</code></pre>
<p>Because of the flushing and exporting level setting, by default when you call <code>Yii::trace()</code> or any other logging
method, you will NOT see the log message immediately in the log targets. This could be a problem for some long-running
console applications. To make each log message appear immediately in the log targets, you should set both
<a href="./yii-log-dispatcher.html#$flushInterval-detail">flushInterval</a> and <a href="./yii-log-target.html#$exportInterval-detail">exportInterval</a> to be 1,
as shown below:</p>
<pre><code class="hljs php language-php"><span class="hljs-keyword">return</span> [
    <span class="hljs-string">'bootstrap'</span> =&gt; [<span class="hljs-string">'log'</span>],
    <span class="hljs-string">'components'</span> =&gt; [
        <span class="hljs-string">'log'</span> =&gt; [
            <span class="hljs-string">'flushInterval'</span> =&gt; <span class="hljs-number">1</span>,
            <span class="hljs-string">'targets'</span> =&gt; [
                [
                    <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\log\FileTarget'</span>,
                    <span class="hljs-string">'exportInterval'</span> =&gt; <span class="hljs-number">1</span>,
                ],
            ],
        ],
    ],
];
</code></pre>
<blockquote class="note"><p><strong>Note: </strong>Frequent message flushing and exporting will degrade the performance of your application.</p>
</blockquote>
<h3>Toggling Log Targets  <span id="toggling-log-targets"></span><a href="#toggling-log-targets" class="hashlink">&para;</a></h3><p>You can enable or disable a log target by configuring its <a href="./yii-log-target.html#$enabled-detail">enabled</a> property.
You may do so via the log target configuration or by the following PHP statement in your code:</p>
<pre><code class="hljs php language-php">Yii::<span class="hljs-variable">$app</span>-&gt;log-&gt;targets[<span class="hljs-string">'file'</span>]-&gt;enabled = <span class="hljs-keyword">false</span>;
</code></pre>
<p>The above code requires you to name a target as <code>file</code>, as shown below by using string keys in the
<code>targets</code> array:</p>
<pre><code class="hljs php language-php"><span class="hljs-keyword">return</span> [
    <span class="hljs-string">'bootstrap'</span> =&gt; [<span class="hljs-string">'log'</span>],
    <span class="hljs-string">'components'</span> =&gt; [
        <span class="hljs-string">'log'</span> =&gt; [
            <span class="hljs-string">'targets'</span> =&gt; [
                <span class="hljs-string">'file'</span> =&gt; [
                    <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\log\FileTarget'</span>,
                ],
                <span class="hljs-string">'db'</span> =&gt; [
                    <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\log\DbTarget'</span>,
                ],
            ],
        ],
    ],
];
</code></pre>
<h3>Creating New Targets  <span id="new-targets"></span><a href="#new-targets" class="hashlink">&para;</a></h3><p>Creating a new log target class is very simple. You mainly need to implement the <a href="./yii-log-target.html#export()-detail">yii\log\Target::export()</a> method
sending the content of the <a href="./yii-log-target.html#$messages-detail">yii\log\Target::$messages</a> array to a designated medium. You may call the
<a href="./yii-log-target.html#formatMessage()-detail">yii\log\Target::formatMessage()</a> method to format each message. For more details, you may refer to any of the
log target classes included in the Yii release.</p>
<h2>Performance Profiling  <span id="performance-profiling"></span><a href="#performance-profiling" class="hashlink">&para;</a></h2><p>Performance profiling is a special type of message logging that is used to measure the time taken by certain
code blocks and find out what are the performance bottlenecks. For example, the <a href="./yii-db-command.html">yii\db\Command</a> class uses
performance profiling to find out the time taken by each DB query.</p>
<p>To use performance profiling, first identify the code blocks that need to be profiled. Then enclose each
code block like the following:</p>
<pre><code class="hljs php language-php">\Yii::beginProfile(<span class="hljs-string">'myBenchmark'</span>);

...code block being profiled...

\Yii::endProfile(<span class="hljs-string">'myBenchmark'</span>);
</code></pre>
<p>where <code>myBenchmark</code> stands for a unique token identifying a code block. Later when you examine the profiling
result, you will use this token to locate the time spent by the corresponding code block.</p>
<p>It is important to make sure that the pairs of <code>beginProfile</code> and <code>endProfile</code> are properly nested.
For example,</p>
<pre><code class="hljs php language-php">\Yii::beginProfile(<span class="hljs-string">'block1'</span>);

    <span class="hljs-comment">// some code to be profiled</span>

    \Yii::beginProfile(<span class="hljs-string">'block2'</span>);
        <span class="hljs-comment">// some other code to be profiled</span>
    \Yii::endProfile(<span class="hljs-string">'block2'</span>);

\Yii::endProfile(<span class="hljs-string">'block1'</span>);
</code></pre>
<p>If you miss <code>\Yii::endProfile('block1')</code> or switch the order of <code>\Yii::endProfile('block1')</code> and
<code>\Yii::endProfile('block2')</code>, the performance profiling will not work.</p>
<p>For each code block being profiled, a log message with the severity level <code>profile</code> is recorded. You can configure
a <a href="#log-targets">log target</a> to collect such messages and export them. The <a href="guide-tool-debugger.html">Yii debugger</a> has
a built-in performance profiling panel showing the profiling results.</p>
        <div class="toplink"><a href="#" class="h1" title="go to top"><span class="glyphicon glyphicon-arrow-up"></a></div>
    </div>
</div>


</div>

<footer class="footer">
        <p class="pull-right"><small>Page generated on Sat, 09 Jul 2016 12:16:29 +0000</small></p>
    Powered by <a href="http://www.yiiframework.com/" rel="external">Yii Framework</a></footer>

<script type="text/javascript">jQuery(document).ready(function () {
    var shiftWindow = function () { scrollBy(0, -50) };
    if (location.hash) setTimeout(shiftWindow, 1);
    window.addEventListener("hashchange", shiftWindow);
var element = document.createElement("script");
element.src = "./jssearch.index.js";
document.body.appendChild(element);

var searchBox = $('#searchbox');

// search when typing in search field
searchBox.on("keyup", function(event) {
    var query = $(this).val();

    if (query == '' || event.which == 27) {
        $('#search-resultbox').hide();
        return;
    } else if (event.which == 13) {
        var selectedLink = $('#search-resultbox a.selected');
        if (selectedLink.length != 0) {
            document.location = selectedLink.attr('href');
            return;
        }
    } else if (event.which == 38 || event.which == 40) {
        $('#search-resultbox').show();

        var selected = $('#search-resultbox a.selected');
        if (selected.length == 0) {
            $('#search-results').find('a').first().addClass('selected');
        } else {
            var next;
            if (event.which == 40) {
                next = selected.parent().next().find('a').first();
            } else {
                next = selected.parent().prev().find('a').first();
            }
            if (next.length != 0) {
                var resultbox = $('#search-results');
                var position = next.position();

//              TODO scrolling is buggy and jumps around
//                resultbox.scrollTop(Math.floor(position.top));
//                console.log(position.top);

                selected.removeClass('selected');
                next.addClass('selected');
            }
        }

        return;
    }
    $('#search-resultbox').show();
    $('#search-results').html('<li><span class="no-results">No results</span></li>');

    var result = jssearch.search(query);

    if (result.length > 0) {
        var i = 0;
        var resHtml = '';

        for (var key in result) {
            if (i++ > 20) {
                break;
            }
            resHtml = resHtml +
            '<li><a href="' + result[key].file.u.substr(3) +'"><span class="title">' + result[key].file.t + '</span>' +
            '<span class="description">' + result[key].file.d + '</span></a></li>';
        }
        $('#search-results').html(resHtml);
    }
});

// hide the search results on ESC
$(document).on("keyup", function(event) { if (event.which == 27) { $('#search-resultbox').hide(); } });
// hide search results on click to document
$(document).bind('click', function (e) { $('#search-resultbox').hide(); });
// except the following:
searchBox.bind('click', function(e) { e.stopPropagation(); });
$('#search-resultbox').bind('click', function(e) { e.stopPropagation(); });

});</script></body>
</html>
